﻿Ultra Tools Textbox 사용 메뉴얼
=========================

1. 노드 소개
------------
Ultra Tools Textbox는 ComfyUI에서 문자열(STRING)을 직접 작성하거나 다른 텍스트 노드에서 받아서 전달하는 텍스트 전용 노드입니다.

기본 상태에서는 Text 1 하나만 표시되며, 필요할 때 아래의 "＋ 텍스트 추가" 버튼을 눌러 Text 2, Text 3 ... 형태로 텍스트 칸을 늘릴 수 있습니다.
각 Text는 서로 독립된 입력(IN)과 출력(OUT)을 사용합니다.

예)
- IN 1  -> Text 1 -> OUT 1
- IN 2  -> Text 2 -> OUT 2
- IN 3  -> Text 3 -> OUT 3

따라서 한 개의 노드에서 여러 개의 서로 다른 문자열을 독립적으로 관리하고 전달할 수 있습니다.


2. 기본 사용 방법
-----------------
1) 노드를 추가합니다.
   노드 이름: Ultra Tools Textbox
   카테고리: Ultra Tools

2) Text 1 입력 칸에 원하는 문장을 직접 작성합니다.

3) OUT 1을 STRING 입력을 받는 다른 ComfyUI 노드에 연결합니다.

4) 큐를 실행하면 Text 1의 내용이 OUT 1을 통해 그대로 전달됩니다.

문장, 프롬프트, 태그, JSON처럼 보이는 문자열, 여러 줄 텍스트, 한글/영문/일본어/이모지 등 일반 STRING으로 처리할 수 있는 내용은 그대로 사용할 수 있습니다.


3. 여러 개의 Text 사용
----------------------
노드 아래의 "＋ 텍스트 추가" 버튼을 누르면 Text가 순서대로 추가됩니다.

예)
Text 1
Text 2
Text 3

Text가 추가될 때마다 대응하는 입력과 출력도 함께 추가됩니다.

- Text 1 = IN 1 / OUT 1
- Text 2 = IN 2 / OUT 2
- Text 3 = IN 3 / OUT 3

화면에는 현재 사용 중인 Text 개수에 맞는 입력/출력만 표시됩니다.
사용하지 않는 빈 출력 슬롯이 길게 나열되지 않습니다.

최대 32개의 Text를 사용할 수 있습니다.


4. 직접 입력과 IN 입력의 차이
-----------------------------
각 Text는 두 가지 방법으로 값을 사용할 수 있습니다.

A. 직접 입력
Text 입력 칸에 사용자가 직접 문자열을 작성합니다.
해당 문자열이 대응하는 OUT으로 전달됩니다.

B. IN 단자 연결
다른 STRING 출력 노드를 IN 1, IN 2 ...에 연결할 수 있습니다.
IN이 연결된 Text는 실행할 때 외부에서 받은 문자열이 우선 사용됩니다.

중요한 점:
이 노드는 일반 multiline 위젯을 입력 단자로 변환했을 때처럼 텍스트 칸을 회색 읽기 전용 상태로 만들지 않습니다.
외부 STRING을 받아도 해당 Text 칸은 일반 직접 입력 상태와 같은 모습으로 유지되며 계속 편집할 수 있습니다.

실행 후에는 실제로 받은 문자열이 해당 Text 칸에 표시됩니다.
따라서 외부 노드에서 어떤 문자열이 전달되었는지 눈으로 확인하고, 복사하거나 직접 수정할 수 있습니다.


5. IN 연결 상태에서 직접 수정할 때
---------------------------------
IN이 연결되어 있어도 Text 칸을 직접 수정할 수 있습니다.

다만 실행 시에는 연결된 IN의 값이 우선입니다.

예)
1) Text 2의 IN 2에서 "ABC"가 들어옵니다.
2) 실행 후 Text 2에는 ABC가 표시됩니다.
3) 사용자가 Text 2를 직접 "DEF"로 수정할 수 있습니다.
4) IN 2가 계속 연결된 상태에서 다시 실행하면 상위 노드의 값이 다시 들어옵니다.
5) 상위 노드가 여전히 ABC를 보내고 있다면 Text 2도 다시 ABC로 동기화됩니다.

즉 연결 상태의 Text 칸은 "받은 값을 확인하고 편집할 수 있는 표시/편집 공간"이지만, 실제 다음 실행에서는 연결된 IN 값이 우선한다는 점을 기억하면 됩니다.

IN 연결을 해제하면 현재 Text 칸에 저장된 문자열을 직접 입력값으로 계속 사용할 수 있습니다.


6. OUT 출력 규칙
----------------
각 출력은 같은 번호의 Text만 담당합니다.

- OUT 1은 Text 1의 문자열
- OUT 2는 Text 2의 문자열
- OUT 3은 Text 3의 문자열

Text끼리 자동으로 합치거나 섞지 않습니다.
각 출력은 독립된 STRING 한 개입니다.

예)
Text 1 = positive prompt
Text 2 = negative prompt
Text 3 = file prefix

이라면 각각의 OUT을 원하는 서로 다른 STRING 입력 노드에 연결하면 됩니다.

OUT에 표시되는 이름(라벨)은 실제 데이터 흐름과는 무관한 표시용 텍스트입니다.
이름을 직접 지정하거나 변수명 ON/OFF를 바꿔도 어떤 Text가 어느 OUT으로 나가는지는 항상 번호로 고정되어 있으며 바뀌지 않습니다. (자세한 내용은 8-1, 8-2 참고)


7. Text 삭제
------------
Text가 두 개 이상일 때 각 행에는 × 삭제 버튼이 나타납니다.
원하는 Text를 직접 삭제할 수 있으므로 마지막 Text부터 순서대로 지울 필요가 없습니다.

예)
Text 1
Text 2
Text 3
Text 4

여기서 Text 2의 ×를 누르면 Text 2만 삭제됩니다.
남은 항목은 다음처럼 다시 번호가 정리됩니다.

기존 Text 1 -> 새 Text 1
기존 Text 3 -> 새 Text 2
기존 Text 4 -> 새 Text 3

삭제한 행의 입력 연결과 출력 연결은 함께 제거됩니다.
뒤쪽에 있던 다른 Text들의 기존 연결은 해당 Text를 따라 유지되며 번호만 앞으로 당겨집니다.

이 동작 때문에 중간에 마음에 들지 않는 문장만 골라서 삭제할 수 있습니다.

Text가 하나만 남아 있을 때는 삭제 버튼이 숨겨집니다.
노드는 항상 최소 한 개의 Text를 유지합니다.


8. Copy 버튼
------------
각 Text 오른쪽의 Copy 버튼은 해당 Text 한 개의 내용만 클립보드로 복사합니다.

Copy 버튼은 Text가 한 개일 때와 여러 개일 때 모두 같은 우측 기준선에 배치되도록 되어 있습니다.

복사에 성공하면 잠시 "Copied"로 표시된 뒤 다시 "Copy"로 돌아옵니다.
연속해서 빠르게 여러 번 눌러도 최종적으로 Copy 표시로 정상 복원됩니다.


8-1. Text 이름 직접 지정 (라벨 변경)
------------------------------------
각 Text 행 왼쪽의 이름("Text 1" 등)을 클릭하면 이름을 직접 입력할 수 있습니다.

- Enter: 입력한 이름으로 확정
- Esc 또는 입력칸 밖 클릭: 변경 취소
- 이름을 비운 채 확정하면 기본 이름("Text N")으로 되돌아갑니다.

이름을 지정하면 두 곳에 반영됩니다.
1) 행 왼쪽 라벨이 "1 행동"처럼 "번호 + 지정한 이름"으로 표시됩니다.
2) 오른쪽 OUT 소켓에 표시되는 이름도 지정한 이름으로 함께 바뀝니다.
   (긴 이름은 소켓 폭에 맞게 말줄임표(…)로 줄어들 수 있습니다. 전체 이름은 행 라벨에서 확인할 수 있습니다.)

이 지정 이름은 노드 자신의 상태만 보고 결정되며, 연결된 다른 노드의 이름을 자동으로 따라가지는 않습니다.
즉 IN/OUT을 다른 노드에 연결하거나 연결을 끊어도 한 번 지정한 이름은 사용자가 직접 지우기 전까지 그대로 유지됩니다.


8-2. 변수명 ON/OFF (OUT 기본 표시 전환)
----------------------------------------
노드 상단 오른쪽에는 "변수명 ON" / "변수명 OFF" 버튼이 있습니다.

이 버튼은 위 8-1에서 이름을 지정하지 않은 행에만 영향을 줍니다.
이미 이름을 지정한 행은 이 버튼 상태와 무관하게 항상 지정한 이름을 계속 표시합니다.

- 변수명 OFF (기본값): 이름을 지정하지 않은 행의 OUT 소켓은 "OUT 1", "OUT 2" ... 로 표시됩니다.
- 변수명 ON: 같은 행의 OUT 소켓이 백엔드에서 실제로 사용하는 변수명인 "Text 1", "Text 2" ... 로 표시됩니다.

워크플로우를 다시 열어도 이 설정은 노드별로 그대로 유지됩니다.


8-3. Text 순서 교체 (⋀ ⋁)
---------------------------
각 행 헤더의 ⋀(위로) ⋁(아래로) 버튼을 누르면 바로 위/아래 Text와 순서를 서로 바꿀 수 있습니다.

- 내용(작성한 텍스트)과 지정한 이름이 함께 이동합니다.
- 각 Text에 연결되어 있던 IN/OUT 링크도 내용을 그대로 따라갑니다.
  즉 순서를 바꿔도 "어떤 문자열이 어느 노드로 전달되는지"는 바뀌지 않고, 화면상 위치만 바뀝니다.
- 맨 위 Text는 ⋀ 버튼이, 맨 아래 Text는 ⋁ 버튼이 비활성화됩니다.


9. 노드 크기와 Text 영역
------------------------
Text를 추가하면 필요한 만큼 노드 높이가 증가합니다.
현재 표시 중인 Text 입력칸들은 서로 같은 높이로 배치됩니다.

노드 높이를 사용자가 직접 늘리거나 줄이면 각 Text 입력칸도 함께 같은 높이로 조정됩니다.
그 상태에서 Text를 추가하면 새 입력칸도 현재 입력칸과 같은 높이로 생기며, Text를 삭제해도 남아 있는 입력칸의 높이는 바뀌지 않습니다.
즉 추가/삭제를 반복해도 Text 입력칸의 높이가 조금씩 커지거나 작아지지 않도록 구성되어 있습니다.

입력/출력 슬롯은 ComfyUI의 기본 슬롯 배치 방식을 사용합니다.
커스텀 좌표로 슬롯을 억지로 이동시키지 않으므로 보이는 단자와 실제 마우스 연결 위치가 서로 어긋나지 않도록 설계되어 있습니다.


10. 워크플로우 저장과 복원
--------------------------
Text의 개수와 각 Text의 내용은 워크플로우에 저장됩니다.

예)
Text 1 = A
Text 2 = B
Text 3 = C

상태로 워크플로우를 저장하면 다시 열었을 때 세 개의 Text와 각 문자열이 복원됩니다.

내부적으로는 멀티 Text 상태를 별도의 명시적인 상태 마커와 함께 저장합니다.
따라서 사용자가 직접 입력한 일반 JSON 문자열을 멀티 Text 데이터로 함부로 오인하지 않도록 되어 있습니다.

예를 들어 아래 내용도 그냥 Text 1의 일반 문자열로 취급됩니다.
{"prompt":"hello"}
["a","b","c"]


11. 기존 단일 Ultra Tools Textbox 호환
-------------------------------
기존 단일 Ultra Tools Textbox에서 저장한 일반 텍스트는 새 멀티 버전에서 Text 1로 불러옵니다.

구형 워크플로우에서 기존 multiline 텍스트 위젯 자체를 입력으로 변환해 연결했던 경우에도, 가능한 경우 그 연결을 새 전용 IN 1로 이전하도록 호환 처리가 포함되어 있습니다.

현재 버전에서는 상태 저장용 내부 위젯의 연결 슬롯을 화면에서 사용하지 않으므로, STRING 연결을 시도할 때 IN 1 근처에 불필요한 입력 후보가 겹쳐 보이는 현상을 방지합니다.


12. 문자열 처리 예
------------------
다음과 같은 내용들을 각각 독립된 STRING으로 사용할 수 있습니다.

- 짧은 단어
- 긴 자연어 프롬프트
- 여러 줄 프롬프트
- 한글/영문 혼합 텍스트
- 일본어/중국어 등 유니코드 문자열
- 이모지
- JSON 형식처럼 보이는 문자열
- 쉼표가 많은 태그 문자열
- 파일명용 문자열
- 다른 커스텀 노드가 생성한 STRING

노드는 문자열의 의미를 해석하거나 수정하지 않고 기본적으로 그대로 전달합니다.


13. 빈 문자열
-------------
Text 칸이 비어 있으면 빈 STRING이 출력됩니다.

IN에 연결된 상위 노드가 빈 문자열을 출력하면 해당 행에도 빈 문자열이 적용됩니다.
빈 문자열이라고 해서 다른 Text의 값이 대신 사용되지는 않습니다.


14. 최대 Text 수
----------------
최대 32개입니다.

32개에 도달하면 추가 버튼은 최대 개수 상태를 표시하며 더 이상 Text를 추가하지 않습니다.
이 제한은 ComfyUI 백엔드의 안정적인 입력/출력 계약과 동적 UI를 함께 유지하기 위한 안전 상한입니다.

화면에는 항상 실제 활성화된 Text 수만큼의 IN/OUT만 보입니다.


15. 설치 방법
-------------
1) comfyui-Ultra-Tools 폴더를 ComfyUI의 custom_nodes 폴더 아래에 둡니다.

예)
ComfyUI/custom_nodes/comfyui-Ultra-Tools/

2) 이 노드와 직접 관련된 주요 파일은 다음과 같습니다.

__init__.py
nodes.py
web/ultra_textbox.js
메뉴얼/Ultra Tools Textbox 메뉴얼.txt

통합 패키지에는 다른 Ultra Tools 노드 파일도 함께 들어 있습니다. 메뉴얼 파일은 참고 문서이므로 없어도 노드 동작에는 영향을 주지 않습니다.

3) ComfyUI를 완전히 재시작합니다.

4) 브라우저에서 ComfyUI 화면을 새로고침합니다.
프런트엔드 JS가 이전 버전으로 캐시되어 보인다면 강력 새로고침을 한 번 해 주십시오.


16. 사용 시 기억할 핵심
-----------------------
- Text 하나당 IN 하나, OUT 하나가 대응합니다.
- 직접 작성하면 작성한 문자열이 출력됩니다.
- IN이 연결되어 있으면 실행 시 IN 문자열이 우선합니다.
- IN으로 받은 문자열도 textarea에 정상 표시되며 편집할 수 있습니다.
- 연결 상태에서 직접 수정해도 다음 실행에서는 IN 값이 다시 우선합니다.
- Text는 ＋ 버튼으로 순차 추가합니다.
- 삭제는 원하는 중간 Text를 직접 ×로 삭제할 수 있습니다.
- 중간 삭제 시 삭제된 행의 연결만 제거되고 뒤 Text의 연결은 유지됩니다.
- 행 왼쪽 이름을 클릭하면 OUT 소켓에 표시될 이름을 직접 지정할 수 있습니다.
- 노드 상단의 "변수명 ON/OFF"는 이름을 지정하지 않은 OUT의 기본 표시(OUT N ↔ Text N)만 전환합니다.
- ⋀⋁ 버튼으로 Text 순서를 바꿀 수 있으며, 내용/이름/연결이 함께 따라 이동합니다.
- Copy는 해당 Text 하나만 복사합니다.
- 최대 32개까지 사용할 수 있습니다.
- Text 개수와 내용은 워크플로우에 저장/복원됩니다.


17. 배포본 설계 원칙
--------------------
이 노드는 단순한 텍스트 도구인 만큼 불필요한 기능을 많이 넣기보다 다음 사항을 우선합니다.

- ComfyUI 기본 STRING 흐름과의 호환
- 입력/출력 대응 관계의 명확성
- 단일 Text 사용 시에도 깔끔한 UI
- 필요할 때만 확장되는 멀티 Text 구조
- 중간 항목을 자유롭게 삭제할 수 있는 편의성
- 외부 STRING 입력을 회색 읽기 전용 칸이 아닌 일반 편집 가능한 Text로 확인
- 저장/재로드 안정성
- 기존 단일 Ultra Tools Textbox 워크플로우의 가능한 범위 내 호환
- ComfyUI 코어 슬롯 배치와 클릭 판정 존중


18. 문제 발생 시 확인 사항
--------------------------
A. 노드 모양이 이전 버전과 섞여 보일 때
- ComfyUI를 완전히 종료 후 재실행합니다.
- 브라우저를 강력 새로고침합니다.
- custom_nodes 안에 기존 `comfyui-Ultra-textbox` 폴더와 새 `comfyui-Ultra-Tools` 폴더가 동시에 설치되어 있지 않은지 확인합니다.

B. IN 연결값이 직접 수정한 문자열로 다시 바뀌는 것처럼 느껴질 때
- IN이 연결되어 있으면 실행 시 외부 입력이 항상 우선입니다.
- 직접 작성한 값을 고정해서 쓰려면 해당 IN 연결을 해제하십시오.

C. 중간 Text를 삭제했을 때
- 삭제한 Text의 IN/OUT 연결은 의도적으로 제거됩니다.
- 뒤 Text는 번호가 앞으로 당겨지지만 자기 연결은 유지됩니다.

D. 추가 버튼이 더 이상 동작하지 않을 때
- 최대 32개에 도달했는지 확인합니다.
